Mastra 是一个 AI 代理框架，其模板项目 weather-agent 实现了一个完整的天气查询和活动推荐系统。

Mastra 架构概览

Mastra 采用了模块化的架构设计，通过中央协调器来管理各个组件之间的交互：

• 配置 Mastra 实例，集成了工作流、代理、存储和日志系统
• 使用内存存储（ :memory: ）用于遥测和评估数据
• 集成了 Pino 日志记录器

// 主入口文件 (index.ts)
export const mastra = new Mastra({
  workflows: { weatherWorkflow },
  agents: { weatherAgent },
  storage: new LibSQLStore({
    url: ":memory:",
  }),
  logger: new PinoLogger({
    name: 'Mastra',
    level: 'info',
  }),
});

组件调用关系与流程控制

Workflow 流程控制

Workflow 是 Mastra 的核心流程编排器，采用链式调用模式

流程控制特点：

• 顺序执行 ：使用 .then() 方法链式连接步骤
• 数据流转 ：前一步的输出自动成为下一步的输入
• 类型安全 ：通过 Zod schema 验证输入输出数据
• 错误处理 ：任何步骤失败都会中断整个流程

// 天气工作流 (workflows/weather-workflow.ts)
const weatherWorkflow = createWorkflow({
  id: 'weather-workflow',
  inputSchema: z.object({
    city: z.string().describe('The city to get the weather for'),
  }),
  outputSchema: z.object({
    activities: z.string(),
  }),
})
  .then(fetchWeather)
  .then(planActivities);

自动化的两步骤工作流：

• 步骤 1：获取天气预报 ( fetchWeather )

  • 输入：城市名称
  • 处理：地理编码 + 天气数据获取
  • 输出：结构化的天气预报数据

• 步骤 2：规划活动 ( planActivities )

  • 输入：天气预报数据
  • 处理：调用天气代理生成个性化活动建议
  • 输出：格式化的活动推荐列表

Step 执行机制

每个 Step 都有独立的执行上下文，可以访问 Mastra 实例：

// 天气工作流 (workflows/weather-workflow.ts)
const planActivities = createStep({
  id: 'plan-activities',
  description: 'Suggests activities based on weather conditions',
  inputSchema: forecastSchema,
  outputSchema: z.object({
    activities: z.string(),
  }),
  execute: async ({ inputData, mastra }) => {
    // 通过 mastra 实例获取 agent
    const agent = mastra?.getAgent('weatherAgent');
    if (!agent) {
      throw new Error('Weather agent not found');
    }
    
    // 调用 agent 处理业务逻辑
    const response = await agent.stream([{
      role: 'user',
      content: prompt,
    }]);
    
    return { activities: activitiesText };
  },
});

Agent 调用机制

Agent 是智能处理单元，集成了 LLM 和工具能力。

Agent 工作流程：

1. 接收指令 ：通过 agent.stream() 或 agent.generate() 接收用户输入
2. 智能决策 ：LLM 分析是否需要调用工具
3. 工具调用 ：自动调用相关工具获取数据
4. 结果生成 ：基于工具结果生成最终回复

// 天气代理 (agents/weather-agent.ts)
export const weatherAgent = new Agent({
  name: 'Weather Agent',
  instructions: `你是一个天气助手...`,
  model: openai('gpt-4o-mini'),
  tools: { weatherTool },  // 绑定可用工具
  memory: new Memory({
    storage: new LibSQLStore({
      url: 'file:../mastra.db',
    }),
  }),
});

智能对话代理，具备以下特性：

• 使用 OpenAI GPT-4o-mini 模型
• 集成了天气工具能力
• 具备记忆功能（使用 LibSQL 存储）
• 智能处理用户查询，包括位置翻译和活动建议

Tool 调用机制

Tool 是原子化的功能单元，提供具体的能力

// 天气工具 (tools/weather-tool.ts)
export const weatherTool = createTool({
  id: 'get-weather',
  description: 'Get current weather for a location',
  inputSchema: z.object({
    location: z.string().describe('City
    name'),
  }),
  outputSchema: z.object({
    temperature: z.number(),
    feelsLike: z.number(),
    // ... 其他字段
  }),
  execute: async ({ context }) => {
    return await getWeather(context.
    location);
  },
});

核心功能：

• 地理编码 ：通过 Open-Meteo API 将城市名称转换为经纬度坐标
• 天气数据获取 ：获取当前天气信息（温度、湿度、风速等）
• 天气状态映射 ：将天气代码转换为可读的天气描述

完整系统调用流程

1. 用户输入 ：提供城市名称

2. Workflow 启动

   1. fetchWeather Step 执行（地理编码、天气获取、数据处理，格式化天气信息）
   2. planActivities Step 执行（获取 Agent、构建包含天气数据的 prompt、Agent 调用 LLM 生成活动建议）
3. Workflow 完成，输出返回的结构化的活动推荐

核心设计原则

1. 依赖注入

• Mastra 实例作为中央容器管理所有组件
• Step 通过 mastra 参数访问其他组件
• 松耦合设计，便于测试和扩展

2. 类型安全

• 使用 Zod schema 定义输入输出类型
• 编译时类型检查，运行时数据验证
• 确保数据流转的正确性

3. 异步流控制

• 所有操作都是异步的
• 支持流式处理（如 Agent 的 stream 模式）
• 错误会自动传播并中断流程

4. 可观测性

• 集成日志系统（PinoLogger）
• 存储执行遥测数据
• 支持性能监控和调试

这种架构设计使得 Mastra 能够灵活地组合不同的 AI 能力，同时保持代码的可维护性和可扩展性。每个组件都有明确的职责边界，通过标准化的接口进行交互，形成了一个强大而灵活的 AI 应用开发框架。